home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / Other Langs / Tickle-4.0 (tcl) / library / help / tcl / math / expr next >
Encoding:
Text File  |  1993-10-26  |  12.5 KB  |  267 lines  |  [TEXT/$Tcl]
  1.  
  2.           expr arg ?arg arg ...?
  3.  
  4.  
  5.      DESCRIPTION
  6.           Concatenates arg's (adding separator spaces  between  them),
  7.           evaluates  the  result  as a Tcl expression, and returns the
  8.           value.  The operators permitted in  Tcl  expressions  are  a
  9.           subset of the operators permitted in C expressions, and they
  10.           have the same meaning and precedence as the corresponding  C
  11.           operators.   Expressions almost always yield numeric results
  12.           (integer  or  floating-point  values).   For  example,   the
  13.           expression
  14.  
  15.                expr 8.2 + 6
  16.  
  17.           evaluates to 14.2.  Tcl expressions differ  from  C  expres-
  18.           sions  in  the  way  that operands are specified.  Also, Tcl
  19.           expressions support non-numeric  operands  and  string  com-
  20.           parisons.
  21.  
  22.      OPERANDS
  23.           A Tcl expression consists  of  a  combination  of  operands,
  24.           operators, and parentheses.  White space may be used between
  25.           the operands and operators and parentheses; it is ignored by
  26.           the  expression  processor.   Where  possible,  operands are
  27.           interpreted as integer values.  Integer values may be speci-
  28.           fied  in  decimal  (the normal case), in octal (if the first
  29.           character of the operand is 0), or in  hexadecimal  (if  the
  30.           first  two characters of the operand are 0x).  If an operand
  31.           does not have one of the integer formats given  above,  then
  32.           it  is  treated as a floating-point number if that is possi-
  33.           ble.  Floating-point numbers may be specified in any of  the
  34.           ways  accepted  by an ANSI-compliant C compiler (except that
  35.           the ``f'', ``F'', ``l'', and ``L'' suffixes will not be per-
  36.           mitted in most installations).  For example, all of the fol-
  37.           lowing are valid  floating-point  numbers:   2.1,  3.,  6e4,
  38.           7.91e+16.  If no numeric interpretation is possible, then an
  39.           operand is left as a string  (and  only  a  limited  set  of
  40.           operators may be applied to it).
  41.  
  42.           Operands may be specified in any of the following ways:
  43.  
  44.           [1]  As an numeric value, either integer or floating-point.
  45.  
  46.           [2]  As a Tcl variable,  using  standard  $  notation.   The
  47.                variable's value will be used as the operand.
  48.  
  49.           [3]  As a string enclosed in double-quotes.  The  expression
  50.                parser  will  perform  backslash, variable, and command
  51.                substitutions on the information  between  the  quotes,
  52.                and use the resulting value as the operand
  53.  
  54.           [4]  As a string enclosed in braces.  The characters between
  55.                the open brace and matching close brace will be used as
  56.                the operand without any substitutions.
  57.  
  58.           [5]  As a Tcl command enclosed  in  brackets.   The  command
  59.                will  be  executed  and  its result will be used as the
  60.                operand.
  61.  
  62.           [6]  As a mathematical function whose arguments have any  of
  63.                the above forms for operands, such as ``sin($x)''.  See
  64.                below for a list of defined functions.
  65.  
  66.           Where  substitutions  occur  above   (e.g.   inside   quoted
  67.           strings),  they  are  performed by the expression processor.
  68.           However, an additional layer  of  substitution  may  already
  69.           have been performed by the command parser before the expres-
  70.           sion processor was called.  As discussed below, it  is  usu-
  71.           ally  best  to  enclose expressions in braces to prevent the
  72.           command parser from performing  substitutions  on  the  con-
  73.           tents.
  74.  
  75.           For some examples of simple expressions, suppose  the  vari-
  76.           able  a  has the value 3 and the variable b has the value 6.
  77.           Then the command on the left side of each of the lines below
  78.           will produce the value on the right side of the line:
  79.  
  80.                expr 3.1 + $a           6.1
  81.                expr 2 + "$a.$b"        5.6
  82.                expr 4*[llength "6 2"]  8
  83.                expr {word one} < "word $a"0
  84.  
  85.      OPERATORS
  86.           The valid operators are listed below, grouped in  decreasing
  87.           order of precedence:
  88.  
  89.           -  ~  !             Unary minus, bit-wise NOT, logical  NOT.
  90.                               None of these operands may be applied to
  91.                               string operands, and bit-wise NOT may be
  92.                               applied only to integers.
  93.  
  94.           *  /  %             Multiply, divide,  remainder.   None  of
  95.                               these  operands may be applied to string
  96.                               operands, and remainder may  be  applied
  97.                               only  to  integers.   The remainder will
  98.                               always have the same sign as the divisor
  99.                               and  an  absolute value smaller than the
  100.                               divisor.
  101.  
  102.           +  -                Add and subtract.  Valid for any numeric
  103.                               operands.
  104.  
  105.           <<  >>              Left and right shift.  Valid for integer
  106.                               operands only.
  107.  
  108.           <  >  <=  >=        Boolean  less,  greater,  less  than  or
  109.                               equal,  and greater than or equal.  Each
  110.                               operator produces 1 if the condition  is
  111.                               true,  0 otherwise.  These operators may
  112.                               be applied to strings as well as numeric
  113.                               operands,  in  which  case  string  com-
  114.                               parison is used.
  115.  
  116.           ==  !=              Boolean  equal  and  not  equal.    Each
  117.                               operator  produces  a  zero/one  result.
  118.                               Valid for all operand types.
  119.  
  120.           &                   Bit-wise   AND.    Valid   for   integer
  121.                               operands only.
  122.  
  123.           ^                   Bit-wise  exclusive   OR.    Valid   for
  124.                               integer operands only.
  125.  
  126.           |                   Bit-wise OR.  Valid for integer operands
  127.                               only.
  128.  
  129.           &&                  Logical AND.  Produces  a  1  result  if
  130.                               both operands are non-zero, 0 otherwise.
  131.                               Valid   for   numeric   operands    only
  132.                               (integers or floating-point).
  133.  
  134.           ||                  Logical OR.  Produces a 0 result if both
  135.                               operands  are  zero, 1 otherwise.  Valid
  136.                               for numeric operands only  (integers  or
  137.                               floating-point).
  138.  
  139.           x?y:z               If-then-else, as in C.  If  x  evaluates
  140.                               to  non-zero,  then  the  result  is the
  141.                               value of y.  Otherwise the result is the
  142.                               value  of  z.  The x operand must have a
  143.                               numeric value.
  144.  
  145.           See the C manual for more details on the results produced by
  146.           each  operator.   All of the binary operators group left-to-
  147.           right within the same precedence level.   For  example,  the
  148.           command
  149.  
  150.                expr 4*2 < 7
  151.           returns 0.
  152.  
  153.           The &&, ||, and ?: operators have ``lazy evaluation'',  just
  154.           as in C, which means that operands are not evaluated if they
  155.           are not needed to determine the outcome.   For  example,  in
  156.           the command
  157.  
  158.                expr {$v ? [a] : [b]}
  159.  
  160.           only one of [a] or [b] will actually be evaluated, depending
  161.           on  the  value of $v.  Note, however, that this is only true
  162.           if the entire expression is enclosed in  braces;   otherwise
  163.           the  Tcl parser will evaluate both [a] and [b] before invok-
  164.           ing the expr command.
  165.  
  166.      MATH FUNCTIONS
  167.           Tcl supports the following mathematical functions in expres-
  168.           sions:
  169.  
  170.                acos        cos         hypot      sinh
  171.                asin        cosh        log        sqrt
  172.                atan        exp         log10      tan
  173.                atan2       floor       pow        tanh
  174.                ceil        fmod        sin
  175.           Each of these functions invokes the math library function of
  176.           the same name;  see the manual entries for the library func-
  177.           tions for details on what they do.  Tcl also implements  the
  178.           following  functions  for  conversion  between  integers and
  179.           floating-point numbers:
  180.  
  181.           abs(arg)
  182.                Returns the absolute value of arg.  Arg may  be  either
  183.                integer  or  floating-point, and the result is returned
  184.                in the same form.
  185.  
  186.           double(arg)
  187.                If arg is a floating value, returns arg, otherwise con-
  188.                verts arg to floating and returns the converted value.
  189.  
  190.           int(arg)
  191.                If arg is an integer value, returns arg, otherwise con-
  192.                verts arg to integer by truncation and returns the con-
  193.                verted value.
  194.  
  195.           round(arg)
  196.                If arg is an integer value, returns arg, otherwise con-
  197.                verts  arg  to integer by rounding and returns the con-
  198.                verted value.
  199.  
  200.           In addition to these predifined functions, applications  may
  201.           define additional functions using Tcl_CreateMathFunc().
  202.  
  203.      TYPES, OVERFLOW, AND PRECISION
  204.           All internal computations involving integers are  done  with
  205.           the  C  type  long,  and all internal computations involving
  206.           floating-point are done with the C type double.   When  con-
  207.           verting  a  string  to  floating-point, exponent overflow is
  208.           detected and results in a  Tcl  error.   For  conversion  to
  209.           integer  from  string,  detection of overflow depends on the
  210.           behavior of some routines in the  local  C  library,  so  it
  211.           should  be  regarded  as  unreliable.   In any case, integer
  212.           overflow and underflow are generally not  detected  reliably
  213.           for   intermediate  results.   Floating-point  overflow  and
  214.           underflow are  detected  to  the  degree  supported  by  the
  215.           hardware, which is generally pretty reliable.
  216.  
  217.           Conversion  among  internal  representations  for   integer,
  218.           floating-point, and string operands is done automatically as
  219.           needed.  For  arithmetic  computations,  integers  are  used
  220.           until  some floating-point number is introduced, after which
  221.           floating-point is used.  For example,
  222.  
  223.                expr 5 / 4
  224.           returns 1, while
  225.  
  226.                expr 5 / 4.0
  227.                expr 5 / ( [string length "abcd"] + 0.0 )
  228.  
  229.           both return 1.25.  Floating-point values are always returned
  230.           with  a  ``.''  or  an ``e'' so that they will not look like
  231.           integer values.  For example,
  232.  
  233.                expr 20.0/5.0
  234.           returns   ``4.0'',   not   ``4''.    The   global   variable
  235.           tcl_precision  determines  the  the  number  of  significant
  236.           digits that are retained when floating values are  converted
  237.           to  strings  (except  that trailing zeroes are omitted).  If
  238.           tcl_precision is unset then 6 digits of precision are  used.
  239.           To  retain  all of the significant bits of an IEEE floating-
  240.           point number set tcl_precision to 17;  if a  value  is  con-
  241.           verted  to  string with 17 digits of precision and then con-
  242.           verted back  to  binary  for  some  later  calculation,  the
  243.           resulting  binary value is guaranteed to be identical to the
  244.           original one.
  245.  
  246.  
  247.      STRING OPERATIONS
  248.           String values may be used  as  operands  of  the  comparison
  249.           operators,  although  the  expression  evaluator tries to do
  250.           comparisons as integer or floating-point when  it  can.   If
  251.           one  of  the  operands  of  a comparison is a string and the
  252.           other has a numeric value, the numeric operand is  converted
  253.           back to a string using the C sprintf format specifier %d for
  254.           integers and %g for floating-point values.  For example, the
  255.           commands
  256.  
  257.                expr "0x03" > "2"
  258.                expr "0y" < "0x12"
  259.  
  260.           both return 1.  The first comparison is done  using  integer
  261.           comparison,  and  the second is done using string comparison
  262.           after the second operand is converted to the string ``18''.
  263.  
  264.  
  265.      KEYWORDS
  266.           arithmetic, boolean, compare, expression
  267.